home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / zggbal.z / zggbal
Text File  |  1996-03-14  |  5KB  |  133 lines
  1.  
  2.  
  3.  
  4. ZZZZGGGGGGGGBBBBAAAALLLL((((3333FFFF))))                                                          ZZZZGGGGGGGGBBBBAAAALLLL((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ZGGBAL - balance a pair of general complex matrices (A,B)
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE ZGGBAL( JOB, N, A, LDA, B, LDB, ILO, IHI, LSCALE, RSCALE,
  13.                         WORK, INFO )
  14.  
  15.          CHARACTER      JOB
  16.  
  17.          INTEGER        IHI, ILO, INFO, LDA, LDB, N
  18.  
  19.          DOUBLE         PRECISION LSCALE( * ), RSCALE( * ), WORK( * )
  20.  
  21.          COMPLEX*16     A( LDA, * ), B( LDB, * )
  22.  
  23. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  24.      ZGGBAL balances a pair of general complex matrices (A,B).  This involves,
  25.      first, permuting A and B by similarity transformations to isolate
  26.      eigenvalues in the first 1 to ILO$-$1 and last IHI+1 to N elements on the
  27.      diagonal; and second, applying a diagonal similarity transformation to
  28.      rows and columns ILO to IHI to make the rows and columns as close in norm
  29.      as possible. Both steps are optional.
  30.  
  31.      Balancing may reduce the 1-norm of the matrices, and improve the accuracy
  32.      of the computed eigenvalues and/or eigenvectors in the generalized
  33.      eigenvalue problem A*x = lambda*B*x.
  34.  
  35.  
  36. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  37.      JOB     (input) CHARACTER*1
  38.              Specifies the operations to be performed on A and B:
  39.              = 'N':  none:  simply set ILO = 1, IHI = N, LSCALE(I) = 1.0 and
  40.              RSCALE(I) = 1.0 for i=1,...,N; = 'P':  permute only;
  41.              = 'S':  scale only;
  42.              = 'B':  both permute and scale.
  43.  
  44.      N       (input) INTEGER
  45.              The order of the matrices A and B.  N >= 0.
  46.  
  47.      A       (input/output) COMPLEX*16 array, dimension (LDA,N)
  48.              On entry, the input matrix A.  On exit, A is overwritten by the
  49.              balanced matrix.  If JOB = 'N', A is not referenced.
  50.  
  51.      LDA     (input) INTEGER
  52.              The leading dimension of the array A. LDA >= max(1,N).
  53.  
  54.      B       (input/output) COMPLEX*16 array, dimension (LDB,N)
  55.              On entry, the input matrix B.  On exit, B is overwritten by the
  56.              balanced matrix.  If JOB = 'N', B is not referenced.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ZZZZGGGGGGGGBBBBAAAALLLL((((3333FFFF))))                                                          ZZZZGGGGGGGGBBBBAAAALLLL((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      LDB     (input) INTEGER
  75.              The leading dimension of the array B. LDB >= max(1,N).
  76.  
  77.      ILO     (output) INTEGER
  78.              IHI     (output) INTEGER ILO and IHI are set to integers such
  79.              that on exit A(i,j) = 0 and B(i,j) = 0 if i > j and j =
  80.              1,...,ILO-1 or i = IHI+1,...,N.  If JOB = 'N' or 'S', ILO = 1 and
  81.              IHI = N.
  82.  
  83.      LSCALE  (output) DOUBLE PRECISION array, dimension (N)
  84.              Details of the permutations and scaling factors applied to the
  85.              left side of A and B.  If P(j) is the index of the row
  86.              interchanged with row j, and D(j) is the scaling factor applied
  87.              to row j, then LSCALE(j) = P(j)    for J = 1,...,ILO-1 = D(j)
  88.              for J = ILO,...,IHI = P(j)    for J = IHI+1,...,N.  The order in
  89.              which the interchanges are made is N to IHI+1, then 1 to ILO-1.
  90.  
  91.      RSCALE  (output) DOUBLE PRECISION array, dimension (N)
  92.              Details of the permutations and scaling factors applied to the
  93.              right side of A and B.  If P(j) is the index of the column
  94.              interchanged with column j, and D(j) is the scaling factor
  95.              applied to column j, then RSCALE(j) = P(j)    for J = 1,...,ILO-1
  96.              = D(j)    for J = ILO,...,IHI = P(j)    for J = IHI+1,...,N.  The
  97.              order in which the interchanges are made is N to IHI+1, then 1 to
  98.              ILO-1.
  99.  
  100.      WORK    (workspace) DOUBLE PRECISION array, dimension (6*N)
  101.  
  102.      INFO    (output) INTEGER
  103.              = 0:  successful exit
  104.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  105.  
  106. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  107.      See R.C. WARD, Balancing the generalized eigenvalue problem,
  108.                     SIAM J. Sci. Stat. Comp. 2 (1981), 141-152.
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.